home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / fish / 726-750 / 744 / hextract / hextract.doc < prev    next >
Text File  |  1995-03-18  |  8KB  |  188 lines
  1.                             H E X T R A C T  V1.2 
  2.  
  3.     Hextract provides a means of quickly and easily referencing the mass of
  4.    information contained in header files.
  5.  
  6.     For programmers in C it can give :
  7.      
  8.      Definition of any symbol
  9.      Name of header file containing the symbol.
  10.      Composition of any structure.
  11.      Definitions of structure members.
  12.      Function definitions and arguments.
  13.      Library contents.
  14.      Include.h macros.
  15.          
  16.     Additionally for programmers in Assembler, and to help dis-assembly:
  17.  
  18.      Library offsets & arg registers.
  19.      Structure offsets. 
  20.  
  21.     The data file in this release (headers.z) was constructed mainly from the
  22.    Commodore and Lattice Include_h header files issued with Version 5 of the
  23.    Lattice compiler, with additional data added from the Include_i files.
  24.    Detail of the Arp library is also included.
  25.  
  26.     OPERATION 
  27.  
  28.     Hextract can be called from Workbench or the CLI.  The only general
  29.    requirement is that the executable Hextract and the data file headers.z must
  30.    be in the same directory.   
  31.  
  32.     From a CLI the normal call is just "Hextract" or "Run Hextract".  There is
  33.    one switch - if you call "Hextract <file>"  Hextract will open normally and 
  34.    a decompressed copy of the data file will be placed in <file>.  
  35.  
  36.     The data file at 287 KBytes is pretty substantial and to save space it
  37.    has been compressed (P-Compress) down to only 72K.  Decompression is done
  38.    automatically when Hextract is loaded.  If you have plenty of space on a
  39.    hard disk and prefer to hold the data file in uncompressed form to eliminate
  40.    decompression time when loading, put a decompressed copy of it on the hard
  41.    disk, rename it headers.z and copy Hextract and Hextract.info to the
  42.    same drawer.
  43.  
  44.     Hextract opens a small window and shows the prompt "Enter symbol".  Type in
  45.    the  word to be identified and press return.  Hextract is not case-sensitive
  46.    and recognises the AmigaDOS wildcard ?.  A full-screen output window
  47.    matching your current display will then be opened.  While searching the
  48.    pointer changes to a W.  A complete search will take about 11 secs on an
  49.    A500, and 2 secs on an A3000.
  50.  
  51.     Note that ALL entries should be stripped of everything except the bare 
  52.    name & any preceding underscore.   Enter *()Apple[24] as Apple.
  53.  
  54.     You can continue to use the full window for further entries, or return
  55.    to the small one by entering OK.
  56.  
  57.     To quit the programme type QUIT at the "Enter Symbol" prompt.  To quit 
  58.    while a search is in progress press CONTROL_C.
  59.  
  60.    Defines, Typedefs, structure members
  61.  
  62.     If the word appears in the relevant .h file as a #define or #typedef you
  63.    will get something like:   (MEMF_PUBLIC typed in).
  64.  
  65.        "#define MEMF_PUBLIC (1<<0)"  exec/memory.h  
  66.  
  67.     The entry extracted is shown within inverted commas, and the name of the
  68.    header file added.   
  69.     
  70.     If the word is a member of a structure you get:  (BufBuffer typed in)
  71.  
  72.        WORD  *BufBuffer 8 struct DBufPacket
  73.  
  74.     The figure 8 is the member's offset in the structure.
  75.  
  76.    Structures
  77.  
  78.     To get the composition of a structure, type in the structure name;  
  79.     for example typing in DBufPacket produces:
  80.  
  81.       struct DBufPacket  dbp_  12  graphics/gels.h 
  82.        {
  83.        WORD BufY 0  
  84.        WORD BufX 2  
  85.        struct VSprite *BufPath 4
  86.        WORD *BufBuffer 8
  87.          };
  88.  
  89.     The top line gives the full name of the structure, the prefix used when    
  90.    writing in assembler, where this differs from any .h file prefix, (for 
  91.    example the .i file would show dbp_BufY)  the size in bytes, and the 
  92.    parent header file.  In the line for each member the last figure shows the
  93.    structure offset; if over 10 it will be shown in both decimal and hex.
  94.    
  95.    Structures with nested unions or structures are a bit more complicated. an
  96.    example is the structure MemEntry:
  97.  
  98.       struct MemEntry 8 exec/memory.h
  99.        {
  100.        union {
  101.              ULONG meu_Regs 0
  102.              APTR  meu_Addr 0
  103.              } me_Un ;
  104.       "union me_Un" exec/memory.h
  105.        ULONG me_Length 4
  106.        };
  107.     
  108.     This shows a structure with two members - the union me_Un and the ULONG
  109.    me_Length.  The full name of meu_Regs will be me_Un.meu_Regs.
  110.  
  111.    Functions
  112.  
  113.     If the word is a function the form of the output will vary according to
  114.    whether it is a Lattice or Amiga library function.  Entering Open will
  115.    produce:
  116.  
  117.      "extern int open  __Args((char*,int, ))"   fcntl.h
  118.  
  119.      -30 $fffe2 -$001e  Open(name,accessMode)(D1/D2)  dos.library.h
  120.  
  121.     The equivalent ARP library entry is also given.   The first line details   
  122.    the function open() in the Lattice file fcntl.h, inverted commas show that 
  123.    it is a direct quote from the file.  The second line shows the DOS function
  124.    Open() and gives the library offset in decimal, hex(complement), and hex.
  125.  
  126.    Libraries
  127.  
  128.     If the name of the Library is entered - such as Dos.library or Console.
  129.    device - the full list of functions in the library will be output.
  130.  
  131.    If you are not sure of the spelling of the word you want a decompressed copy
  132.   of headers.z can be loaded into an editor for examination (if you have
  133.   sufficient memory).  You can also add any definitions of your own that you
  134.   might want to reference, or shorten the file by deleting sections that are of
  135.   no value to you.  Note the line FF (line 4924) - this marks the start of the
  136.   library functions section and any non-library additions must be inserted
  137.   before it.  Re-compress the file with P-Compress (Fish #595).
  138.    
  139.    Some header file details have necessarily been omitted from headers.z. 
  140.   These include:
  141.  
  142.      Comments.
  143.      Macros given in the include.i files.
  144.      Proto files.
  145.      Lines beginning #IF, #IFDEF, #IFNDEF, #ENDIF, #ELSE.
  146.  
  147.    The latter may result in two or more apparently conflicting definitions
  148.   of the same item being shown - the various header files will be named so
  149.   that you can find any further information needed.    
  150.      
  151.  
  152.            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  153.  
  154.     Hextract is Freeware.  It may be copied and distributed freely and used
  155.   without charge for non_profit-making purposes.  Authority for profit-making  
  156.   use should be obtained from the author below.
  157.  
  158.     You may use the data file "headers.z" in your programmes, but please note
  159.   that the preparation, formatting and checking of this file accounted for
  160.   most of the work in Hextract, so please clearly say where you got it.
  161.  
  162.     No responsibility can be accepted for any loss occasioned by use of the
  163.   programme.
  164.  
  165.     This release only covers the V1.3 operating system and a V2.0 version may 
  166.   be expected in due course.  
  167.  
  168.     Comments, suggestions, bug-reports all welcome.  (Many thanks to D.W Reisig
  169.   of The Netherlands for his comments and suggestions) .
  170.  
  171.    Chas A. Wyndham,
  172.    1265 Canning Mills Road,
  173.    Roleystone,
  174.    WA 6111.
  175.    Australia 
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.